Skip to content

feat: detect AI coding agents in the user agent - #294

Merged
zentron merged 8 commits into
mainfrom
robe/ai-agent-user-agent
Nov 22, 2026
Merged

zentron merged 8 commits into
mainfrom
robe/ai-agent-user-agent

Conversation

@zentron

@zentron zentron commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Background

AI coding agents increasingly drive tools built on this client, including the Octopus MCP server, but the User-Agent doesn't identify that traffic. Unlike the Go and .NET clients, this client also has no environment detection at all today.

This ports the agent detection added to go-octopusdeploy in OctopusDeploy/go-octopusdeploy#419, so the server sees the same agent names from every client.

Results

When an agent is detected, an (ai-agent=<Name>) comment is appended to the very end of the User-Agent:

ts-octopusdeploy octopus-mcp-server/1.2.3 (claude-code/2.1.42) (ai-agent=ClaudeCode)
  • Appended last, as a comment. Everything before it is byte-for-byte what the client sent before. This matters: Octopus Server identifies the local MCP server by the ts-octopusdeploy octopus-mcp-server prefix, both to enforce the "local MCP disabled" setting and for MCP usage telemetry. An RFC 9110 comment also describes the request rather than presenting the agent as a product/version pair.
  • New aiAgent configuration option. This takes a lesson from the MCP server, which learns the connected agent from the MCP initialize handshake (clientInfo). That's a better signal than environment variables, so callers that know the agent can pass it in. It's mapped to a known name and takes precedence over environment detection; if it isn't recognised, detection falls back to the environment.
  • Then AI_AGENT, the emerging cross-vendor convention, mapped to a known name by prefix (e.g. claude-code_2-1-322_agent → ClaudeCode). A prefix only matches when followed by the end of the value, a separator (-, @, .) or a digit, so amp doesn't match amplitude-mcp.
  • Then vendor variables, checked in a fixed order: Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, OpenCode, Antigravity, Goose, Amp, Cline, Roo Code, Augment, Qwen Code, Factory Droid, Kimi CLI, Trae, Aider and OpenHands.
  • Only a normalised name is sent. An identifier that isn't recognised reports as (ai-agent=Other), and raw values are never included.
  • Detection only runs in Node, inside the existing branch that sets the User-Agent. Browsers are unaffected. It never fails a request: a non-string aiAgent is ignored, and if the environment can't be read no agent is added.
  • Nothing is added when no agent is detected, so existing User-Agents are unchanged.

Testing

  • aiAgent.test.ts covers the edge cases: value-matched rules, excluded variables, nested agents, AI_AGENT formats and precedence, the prefix boundary, the caller-supplied agent, and that raw values never appear. createUserAgent.test.ts checks that appending the agent leaves the existing User-Agent as an exact prefix, and that a non-string aiAgent is ignored.
  • The same test cases, and a shared set of inputs including the prefix boundary cases, give identical results in the Go, .NET and TypeScript clients.
  • tsc and ESLint pass. I only ran the unit test suites, not the integration tests that need a live Octopus instance.

How to review this PR

The logic is in src/aiAgent.ts. createUserAgent.ts replaces the inline string building in axiosAdapter.ts. The agent list is ported from go-octopusdeploy, which is the reference copy; a comment at the top of the file points there.

Caveats

  • Detection is self-reported and spoofable, so it's suitable for analytics, not authorisation or audit decisions.
  • A follow-up in the MCP server can pass clientInfo.name as aiAgent, so its requests carry the normalised name too.

Generated by Claude Code

Report the AI agent driving the client as its own User-Agent token,
between the library and the requesting app:

  ts-octopusdeploy AIAgent/ClaudeCode GitHubActions (release;deploy;v3)

Callers that know the agent from a protocol, such as an MCP server with
the connected client's clientInfo, can pass it as `aiAgent` in the client
configuration. That takes precedence over AI_AGENT, which takes
precedence over vendor-specific environment variables. Only a
normalised agent name is sent. The agent list is ported from
go-octopusdeploy, which is the reference implementation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4ijpGHFpAqBBMhn5WKUq2
zentron and others added 5 commits November 13, 2026 09:41
Merge the identifier prefix table into the agent list so each agent is one entry, keeping two lookups (prefix, then vendor variables) so a self-reported identity still wins. Replace the chained fallback with an explicit return. Behaviour is unchanged, matching review on the .NET port.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4ijpGHFpAqBBMhn5WKUq2
Match the Go and .NET AI_AGENT mapping cases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4ijpGHFpAqBBMhn5WKUq2
Keep edge cases that guard real behaviour plus a happy path, and drop the per-agent table that restated the agent list. The same cases are used in the Go, .NET and TypeScript clients.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4ijpGHFpAqBBMhn5WKUq2
Comment thread src/aiAgent.ts Resolved
zentron and others added 2 commits November 19, 2026 14:51
A self-reported identifier now only matches an agent's prefix when the prefix is followed by the end of the identifier or a separator (-, @, .) or digit. Previously a short prefix such as "amp" matched an unrelated identifier such as "amplitude-mcp", and because self-reported identifiers take precedence, that also hid a correct match from vendor variables. Applied the same way in the Go, .NET and TypeScript clients.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4ijpGHFpAqBBMhn5WKUq2
Report the agent as an RFC 9110 comment, (ai-agent=Name), appended at the very end of the User-Agent. Everything before it is byte-for-byte what the client sent before, so servers and tools that match on the start of the header keep working (Octopus Server identifies the local MCP server by the "ts-octopusdeploy octopus-mcp-server" prefix). A comment also avoids presenting the agent as a product/version pair. Applied the same way in the Go, .NET and TypeScript clients.

Also ignore a caller-supplied aiAgent that isn't a string, and never fail a request if the environment can't be read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4ijpGHFpAqBBMhn5WKUq2
@zentron
zentron merged commit 9fabcf3 into main Nov 22, 2026
4 checks passed
@zentron
zentron deleted the robe/ai-agent-user-agent branch November 22, 2026 00:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants